Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Creating a ROS package by hand.

Description: This tutorial explains how to manually create a ROS package.

Tutorial Level: INTERMEDIATE

Next Tutorial: Managing System Dependencies

There is a tool for creating ROS Packages (roscreate-pkg), but, as you will see, there is nothing actually difficult here. roscreate-pkg prevents mistakes and saves effort, but packages are just a directory and a simple XML file.

Now we'll create a new foobar package. This tutorial assumes that we're working in the directory pkgs on your ROS_PACKAGE_PATH.

pkgs$ mkdir foobar
pkgs$ cd foobar

The very first thing we'll do is add our manifest file. The manifest.xml file allows tools like rospack to determine information about what your package depends upon.

Inside of foobar/manifest.xml put the following:

<package>
  <description brief="example package tutorial">A simple tutorial package</description>
  <author>Your Name Here</author>
  <license>BSD</license>
  <depend package="roscpp" />
  <depend package="std_msgs" />
</package>

Now that your package has a manifest, ROS can find it. Try executing the command:

rospack find foobar

If ROS is set up correctly you should see something like: /home/user/ros/pkgs/foobar. This is how ROS finds packages behind the scenes.

Note that this package now also has dependencies on roscpp and std_msgs. To see one example of why specifying these dependencies is useful, try executing the following commands rospack commands:

rospack export --lang=cpp --attrib=cflags foobar
rospack export --lang=cpp --attrib=lflags foobar

When you run these, rospack looks up the dependencies of foobar and generates the necessary list of includes or linking statements to compile and link the executable. These commands are used by the ROS build system to correctly compile and link your packages despite the modular nature of ROS. You'll probably never have to use these directly since our build system takes care of it for you. However, as you can see, they are reasonably easy use if you want to use a different build system.

In order to take advantage of this, we need to make two build files: a Makefile and CMakeLists.txt file.

Inside of foobar/Makefile, put:

include $(shell rospack find mk)/cmake.mk

This tells make that we're going to use CMake instead of Make to build this package.

Now we need the CMakeLists.txt file so that we can use CMake instead. ROS uses CMake for its more powerful flexibility when building across multiple platforms.

In foobar/CMakeLists.txt put:

cmake_minimum_required(VERSION 2.4.6)
include($ENV{ROS_ROOT}/core/rosbuild/rosbuild.cmake)
rosbuild_init()

That's all you need to start building a package in ROS. Of course, if you want it to actually start building something, you're going to need to learn a couple more CMake macros. See our CMakeLists guide for more information.

There is a tool for creating ROS Packages (catkin_create_pkg), but, as you will see, there is nothing actually difficult here. catkin_create_pkg prevents mistakes and saves effort, but packages are just a directory and a simple XML file.

Now we'll create a new foobar package. This tutorial assumes that we're working your catkin workspace and sourcing of the setup file is already done.

catkin_ws_top $ mkdir -p src/foobar
catkin_ws_top $ cd src/foobar

The very first thing we'll do is add our manifest file. The package.xml file allows tools like rospack to determine information about what your package depends upon.

Inside of foobar/package.xml put the following:

<package>
  <name>foobar</name>
  <version>1.2.4</version>
  <description>
  This package provides foo capability.
  </description>
  <maintainer email="foobar@foo.bar.willowgarage.com">PR-foobar</maintainer>
  <license>BSD</license>

  <buildtool_depend>catkin</buildtool_depend>

  <build_depend>roscpp</build_depend>
  <build_depend>std_msgs</build_depend>

  <run_depend>roscpp</run_depend>
  <run_depend>std_msgs</run_depend>
</package>

See also this page from catkin tutorial for further information on catkin/package.xml.

Now that your package has a manifest, ROS can find it. Try executing the command:

rospack find foobar

If ROS is set up correctly you should see something like: /home/user/ros/catkin_ws_top/src/foobar. This is how ROS finds packages behind the scenes.

Note that this package now also has dependencies on roscpp and std_msgs.

Such dependencies are used by catkin to configure packages in the right order.

Now we need the CMakeLists.txt file so that catkin_make, which uses CMake for its more powerful flexibility when building across multiple platforms, builds the package.

In foobar/CMakeLists.txt put:

cmake_minimum_required(VERSION 2.8.3)
project(foobar)
find_package(catkin REQUIRED roscpp std_msgs)
catkin_package()

That's all you need to start building a package in ROS using catkin. Of course, if you want it to actually start building something, you're going to need to learn a couple more CMake macros. See our CMakeLists.txt guide for more information. Also always go back to beginner level tutorial (CreatingPackage and so on) to customize your package.xml and CMakeLists.txt.

ROS 2 Documentation

Wiki

Page

User

Creating a ROS package by hand.